////////////////////////////////////////////////
// DESCRIPTION:
//    PWM definitions for the iMXS CPU
//
// Legal Notices:
//   Copyright (c) 2008, Telliam Consulting, LLC.
//   All rights reserved.
//
//   Redistribution and use in source and binary forms, with or without modification,
//   are permitted provided that the following conditions are met:
//
//   * Redistributions of source code must retain the above copyright notice, this list
//     of conditions and the following disclaimer.
//   * Redistributions in binary form must reproduce the above copyright notice, this
//     list of conditions and the following disclaimer in the documentation and/or other
//     materials provided with the distribution.
//   * Neither the name of Telliam Consulting nor the names of its contributors may be
//     used to endorse or promote products derived from this software without specific
//     prior written permission.
//
//   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
//   EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
//   OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
//   SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
//   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
//   TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 
//   BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
//   CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
//   ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
//   DAMAGE. 
//
using System;
using FusionWare;
using Microsoft.SPOT;
using System.Runtime.CompilerServices;

namespace Freescale.iMXS
{
    /// <summary>Exposes the PWM controller on the Freescale i.MXS</summary>
    /// <remarks>
    /// The HAL must implement the native code portions of this class or
    /// you will get an exception when trying to use it. 
    /// </remarks>
    public class PWM : DisposableObject
    {
        /// <summary>Creates a new instance of the PWM</summary>
        /// <remarks>
        /// The constructor reserves the GPIO pins for the PWM.
        /// If the pins are already reserved (by another instance
        /// of this class or something else) the reservation fails
        /// and throws an exception. Thus, there can be only one
        /// instance of this class at any time. (There is only one
        /// PWM in the silicon so that makes sense.)
        /// </remarks>
        public PWM()
        {
            PWM.Reserve( true );
        }

        #region IDisposable Support
        /// <summary>Handles releasing the pin on Dispose</summary>
        /// <param name="disposing">context of call</param>
        override protected void Dispose( bool disposing )
        {
            if( !base.IsDisposed )
                PWM.Reserve( false );
        }
        #endregion

        /// <summary>Configures and enables the PWM</summary>
        /// <param name="Frequency">Frequency of the PWM output</param>
        /// <param name="Duty">Duty cycle of the output</param>
        /// <remarks>
        /// This method will set the frequency and duty cycle for the
        /// PWM and enable its output if not already enabled.
        /// </remarks>
        public void Configure( uint Frequency, byte Duty )
        {
            if( Duty > 100 )
                throw new ArgumentOutOfRangeException( "Duty > 100" );

            PWM.SetPWM( true, Frequency, Duty );
        }

        /// <summary>Disables the PWM output</summary>
        /// <remarks>
        /// Disables and powersdown the PWM output and controller
        /// </remarks>
        public void Disable()
        {
            PWM.SetPWM( false, 0, 0 );
        }

        #region Native Methods
        [MethodImpl( MethodImplOptions.InternalCall )]
        private extern static void Reserve( bool State );
        [MethodImpl( MethodImplOptions.InternalCall )]
        private extern static void SetPWM( bool Enable, UInt32 Frequency, byte Duty );
        #endregion
    }
}

